feat(skills): give Claude Agents runs the skills attached to their variation - #208

#208 added the Claude Agents skills handler while Agent Skills was still
experimental, so it imported launchdarkly_ai_server.experimental.skills.
This PR removes that module, which broke the handler, its tests and
mypy once main was merged in. The handler itself stays in
launchdarkly_ai_claude_agents.experimental.skills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…e root

The handler is promoted with Agent Skills (#210), so it moves out of
launchdarkly_ai_claude_agents.experimental.skills before its first
release (#208 is unreleased):

- create_claude_agents_skills_handler is exported from
  launchdarkly_ai_claude_agents, from a new skills module. The
  experimental subpackage and its API report are gone.
- It reports claude-agents.createClaudeAgentsSkillsHandler.

Spec: launchdarkly/ai-sdks-monorepo#59.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…e root (#217)

#208 added `create_claude_agents_skills_handler` at
`launchdarkly_ai_claude_agents.experimental.skills`. The spec now
promotes it with Agent Skills (launchdarkly/ai-sdks-monorepo#59,
following #86), and no release has shipped it, so it moves to the
package root with no deprecated alias:

- `create_claude_agents_skills_handler` is exported from
`launchdarkly_ai_claude_agents`, from a new `skills` module (moved from
`experimental/skills.py`). The `experimental` subpackage and its API
report are deleted.
- It reports `claude-agents.createClaudeAgentsSkillsHandler` instead of
`experimental.createClaudeAgentsSkillsHandler`.
- The README section loses its experimental notice, and the example
imports from the package root. agents.md follows.
- Tests: the fresh-interpreter test that the package root never loaded
the experimental module is replaced by one that the root exports the
handler. The usage test, and
`tests/test_never_forwarded_parameters.py`'s module map, use the new
module and ID.

**Phantom usage events (review follow-up).** The handler called the
public `skill_refs` and `write_skills`, so every run with skills also
reported `client.skillRefs` and `client.writeSkills`, calls the customer
never made. This was already on main from #208/#210; this PR makes the
handler a core export, so it fixes it here:

- Core gains a non-reporting `_skill_refs` in
`launchdarkly_ai_server.skills`; `skill_refs` reports and then delegates
to it. Not a public name, so no API report changes.
- The handler uses `_skill_refs` and the existing `_write_skills` from
`launchdarkly_ai_server.skills_fs`, as `skills_watch.py` already does.
- `packages/claude-agents/tests/test_sdk_usage.py` gains a run with
skills, over invoke and stream, that sends only
`claude-agents.createClaudeAgentsSkillsHandler`. The test fails against
the public helpers.

The TypeScript twin is launchdarkly/js-ai-sdk#136, which makes the same
move before it merges and likely has the same usage pattern to fix.

**Tests:** rebased onto `main` after #210 squash-merged, so the branch
carries only its own commits. `make api-report-check` reports every
report current. `make lint`, `make format-check` and `make typecheck`
pass, and the full suite passes locally.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> **`create_claude_agents_skills_handler`** graduates from
`launchdarkly_ai_claude_agents.experimental.skills` to a top-level
**`skills`** module and is re-exported from
**`launchdarkly_ai_claude_agents`**. The experimental subpackage and its
API report are removed; docs and examples import from the package root,
and SDK usage is reported as
**`claude-agents.createClaudeAgentsSkillsHandler`** instead of the
experimental helper id.
> 
> Runs that materialize variation skills no longer emit phantom
**`client.skillRefs`** / **`client.writeSkills`** events. The handler
calls internal **`_skill_refs`** and **`_write_skills`** (core adds
**`_skill_refs`** as the non-reporting body behind public
**`skill_refs`**). New usage tests assert invoke/stream with skills only
records the factory helper.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d288473. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

…riation (#136)

Base is `main`, which now includes #135 (host options) and #159 (Agent
Skills promotion). **This handler is promoted with Agent Skills**, so it
ships from the package root and never from `/experimental` (spec:
launchdarkly/ai-sdks-monorepo#59).

A skill attached to an agent-mode variation never reached a model run
through `createClaudeAgentsHandler`. Measured on Agent SDK 0.3.220 by
reading the CLI's `init` message: skills are *discovered*, but the
handler's `tools: []` removes the `Skill` tool, and no `query({ skills
})` value brings it back.

`createClaudeAgentsSkillsHandler(options)`, exported from
`@launchdarkly/ai-claude-agents`, fixes that. On every invoke and stream
it:
1. Writes `skillRefs(config)` with `writeSkills` (both from
`@launchdarkly/ai-server`), through the store configured with
`setSkillStore`, into
`mkdtemp(<skillsTempDir>/ld-skills-)/launchdarkly/skills`. Pinned
versions are honored.
2. Passes `plugins: [{ type: 'local', path: <dir>/launchdarkly,
skipMcpDiscovery: true }]` and `skills: ['launchdarkly:<key>', …]`, and
appends `Skill` to `tools` (not to `allowedTools`).
3. Removes the directory when the run ends, however it ends.

- **One directory per run.** There's no shared root, no watcher and no
prune. Detaching a skill from a variation takes effect on the next run,
and concurrent runs never share files.
- **Fail closed.** If the reconcile isn't `ok` (no store, store not yet
initialized, a skill withheld by verification, or an absent pin), the
run throws before `query()` and names each skill.
- **No-skills path.** A variation with no skills runs exactly as with
the core handler, and needs no store.
- **Telemetry.** The tool hooks are installed whenever `Skill` is in
`tools`, so a `Skill` call gets an `execute_tool Skill` span.
- **Internal hook.** The handler reaches core through a package-internal
`prepare` hook on `createClaudeAgentsHandlerInternal`, which isn't part
of `createClaudeAgentsHandler`'s public options.
- **Usage ID.** It reports
`claude-agents.createClaudeAgentsSkillsHandler`, not the core factory's
ID.
- **Options.** `ClaudeAgentsSkillsHandlerOptions` is
`ContentCaptureOptions & ClaudeAgentsHostOptions & { skillsTempDir? }`.
`ClaudeAgentsHostOptions` is now exported from the root too.
- **Not covered:** skills through `claudeAgents()`, `claudeGraph()` and
`toClaudeAgents()`. They take the host options (#135) but build the core
handler, so a variation run through them doesn't get its skills. The
README says so.

**Tests:** a new `skills.test.ts` with a mocked `query()` and a real
store, filesystem and OTel provider, plus the usage row in
`sdk-usage.test.ts`. `api-surface/ai-claude-agents.txt` lists the new
names marked `+`. Lint, typecheck, `api:update` / `api:surface` and all
216 claude-agents tests pass locally.

**Verified live:** a model loads the skill with `Skill` in `tools` but
not in `allowedTools`, on invoke and stream, against 11c6cb4. See [the
live-run
comment](#136 (comment)).
The earlier spike also showed that the handler returns the CLI's "Credit
balance is too low" result as a successful output; that's tracked
separately.

**Spec:** TESTING.md §2.x "Claude Agents Skills Integration" and A.21,
in launchdarkly/ai-sdks-monorepo#59. **Python:**
launchdarkly/python-ai-sdk#208 merged it at `experimental.skills`,
unreleased; a follow-up PR moves it to the root.


🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Overview**
> Adds **`createClaudeAgentsSkillsHandler`** so agent-mode Claude runs
can use LaunchDarkly variation **skills**: on each invoke/stream it
writes pinned skill refs from `setSkillStore` into a per-run temp plugin
(`launchdarkly:<key>`), enables the Agent SDK **`Skill`** tool via a
local plugin, and deletes the directory in **`finally`** (including
after stream abandonment or span-processor errors).
> 
> The core handler gains a package-internal **`prepare`** hook on
`createClaudeAgentsHandlerInternal` (`QueryPreparation`: extra `query()`
options, **`extraBuiltins`** on `tools`, cleanup).
**`@launchdarkly/ai-server`** exposes **`skillRefsInternal`** /
**`writeSkillsInternal`** so handler plumbing does not double-count SDK
usage. Variations with no skills behave like
**`createClaudeAgentsHandler`**; skill write/verify failures **fail
closed** before `query()`. **`claudeAgents`**, **`claudeGraph`**, and
**`toClaudeAgents`** are unchanged.
> 
> Also exports **`ClaudeAgentsHostOptions`** /
**`ClaudeAgentsSkillsHandlerOptions`**, README/agents docs, API-surface
entries, and a large **`skills.test.ts`** suite.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
293f11b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Jeff Dupont <jdupont@launchdarkly.com>